---
type: integration
title: '@astrojs/cloudflare'
description: '@astrojs/cloudflare SSR 어댑터를 사용하여 Astro 프로젝트를 배포하는 방법을 알아보세요.'
githubIntegrationURL: 'https://github.com/withastro/adapters/tree/main/packages/cloudflare/'
category: adapter
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

이 어댑터를 사용하면 Astro가 [`hybrid` 또는 `server` 렌더링된 사이트](/ko/basics/rendering-modes/#요청-시-렌더링)를 [Cloudflare](https://www.cloudflare.com/)에 배포할 수 있습니다.

Astro를 [정적 사이트 빌더](/ko/basics/rendering-modes/#사전-렌더링)로 사용하는 경우 어댑터가 필요하지 않습니다.

[Cloudflare Pages 배포 가이드](/ko/guides/deploy/cloudflare/)에서 Astro 사이트를 배포하는 방법을 알아보세요.

## 왜 Astro Cloudflare인가?

[Cloudflare](https://www.cloudflare.com/)는 CDN, 웹 보안 및 기타 서비스를 제공합니다. 이 어댑터는 Astro 빌드 프로세스를 향상하여 Cloudflare를 통한 배포용 프로젝트를 준비합니다.

## 설치

Astro에는 공식 통합 설정을 자동화하는 `astro add` 명령이 포함되어 있습니다. 원하는 경우 대신 [통합을 수동으로 설치](#수동-설치)할 수 있습니다.

Astro 프로젝트에서 SSR을 활성화하려면 `astro add` 명령을 사용하여 Cloudflare 어댑터를 추가하세요. 그러면 `@astrojs/cloudflare`가 설치되고 `astro.config.mjs` 파일이 한 번에 적절하게 변경됩니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add cloudflare
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add cloudflare
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add cloudflare
  ```
  </Fragment>
</PackageManagerTabs>

### 수동 설치

먼저, 선호하는 패키지 관리자를 사용하여 `@astrojs/cloudflare` 어댑터를 프로젝트 종속성에 추가하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/cloudflare
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/cloudflare
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/cloudflare
  ```
  </Fragment>
</PackageManagerTabs>

그런 다음 어댑터와 원하는 [on-demand 렌더링 모드](/ko/basics/rendering-modes/#요청-시-렌더링)를 `astro.config.mjs` 파일에 추가하세요.

```js title="astro.config.mjs" ins={2,5-6}
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});
```

## 옵션

### imageService

<p>
**타입:** `'passthrough' | 'cloudflare' | 'compile'`<br />
**기본값:** `'passthrough'`
</p>

어댑터에서 사용되는 이미지 서비스를 결정합니다. 호환되지 않는 이미지 서비스가 구성되면 어댑터는 기본적으로 `passthrough` 모드로 설정됩니다. 그렇지 않으면 전역적으로 구성된 이미지 서비스를 사용합니다.

* **`cloudflare`:** [Cloudflare Image Resizing](https://developers.cloudflare.com/images/image-resizing/) 서비스를 사용합니다.
* **`passthrough`:** 기존 [`noop`](/ko/guides/images/#무작동-패스스루-서비스-구성) 서비스를 사용합니다.
* **`compile`:** Astro의 기본 서비스 (sharp)를 사용하지만 빌드 시 사전 렌더링된 경로에서만 사용됩니다. 주문형 렌더링 페이지에 대한 SSR 중에는 모든 `astro:assets` 기능이 비활성화됩니다.

```js title="astro.config.mjs" ins={6}
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
     imageService: 'cloudflare'
  }),
  output: 'server'
})
```

### platformProxy

Cloudflare 런타임이 `astro dev`에 추가되는지 여부와 방법을 결정합니다. 여기에는 로컬 `workerd` 바인딩에 대한 프록시와 Cloudflare 특정 값의 에뮬레이션이 포함되어 있어 Node.js 개발 프로세스에서 런타임을 에뮬레이션할 수 있습니다. [Cloudflare 런타임](#cloudflare-런타임)에 대해 자세히 알아보세요.

:::note
제공되는 프록시는 최선을 다해 실제 프로덕션을 에뮬레이션한 것입니다. 최대한 실제와 비슷하게 설계되었으나 약간의 차이와 불일치가 있을 수 있습니다.
:::

#### platformProxy.enabled
<p>
**타입:** `{ enabled?: boolean }`<br />
**기본값:** `{ enabled: false }`
</p>

`enabled` 속성을 사용하면 `astro dev`에서 Cloudflare 런타임을 활성화할 수 있습니다.

#### platformProxy.configPath
<p>
**타입:** `{ configPath?: string }`<br />
**기본값:** `{ configPath: 'wrangler.toml' }`
</p>

`configPath`를 사용하면 Astro 프로젝트의 루트를 기준으로 Wrangler 구성 파일을 정의할 수 있습니다.

#### platformProxy.experimentalJsonConfig
<p>
**타입:** `{ experimentalJsonConfig?: boolean }`<br />
**기본값:** `{ experimentalJsonConfig?: false }`
</p>

`experimentalJsonConfig` 속성은 유틸리티가 JSON 구성 파일 (예: `wrangler.json`)을 읽는지 여부를 정의합니다.

#### platformProxy.persist
<p>
**타입:** `{ persist?: boolean | { path: string } }`<br />
**기본값:** `{ persist: true }`
</p>

`persist` 속성은 바인딩 데이터가 지속되는지 여부와 위치를 정의합니다. `true`는 Wrangler에서 사용하는 것과 동일한 위치를 기본값으로 지정하므로 둘 간에 데이터를 공유할 수 있습니다. `false`인 경우 데이터가 파일 시스템에 저장되지 않고, 파일 시스템에서 읽을 수 없게 됩니다.

:::note
`wrangler`의 `--persist-to` 옵션은 내부적으로 `v3`라는 하위 디렉터리를 추가하지만 `@astrojs/cloudflare` `persist` 속성은 그렇지 않습니다. 예를 들어 `wrangler dev --persist-to ./my-directory`를 실행하는 것과 동일한 위치를 재사용하려면 `persist: "./my-directory/v3"`을 지정해야 합니다.
:::

다음 구성은 개발 서버를 실행할 때 Cloudflare 런타임을 활성화하고 `wrangler.json` 구성 파일 (실험적)을 사용하는 예를 보여줍니다. 또한 파일 시스템에 데이터를 유지하기 위한 사용자 정의 위치를 ​​지정합니다.

```js
import cloudflare from '@astrojs/cloudflare';
import { defineConfig } from 'astro/config';

export default defineConfig({
	adapter: cloudflare({
		platformProxy: {
			enabled: true,
			configPath: 'wrangler.json',
			experimentalJsonConfig: true,
			persist: './.cache/wrangler/v3',
		},
	}),
});
```
### routes.extend

이 옵션을 사용하면 요청 시 생성되는 경로를 결정하기 위해 생성된 [`_routes.json`](#사용자-정의-_routesjson) 파일에 사용자 지정 패턴 (예: `/fonts/*`)을 추가하거나 제외할 수 있습니다. 이는 자동으로 생성할 수 없는 경로 패턴을 추가해야 하거나 사전 렌더링된 경로를 제외해야 하는 경우 유용할 수 있습니다.

사용자 지정 경로 패턴에 대한 자세한 내용은 [Cloudflare의 라우팅 문서](https://developers.cloudflare.com/pages/functions/routing/#functions-invocation-routes)에서 확인할 수 있습니다. 지정된 경로는 자동으로 중복 제거되지 않으며 기존 경로에 그대로 추가됩니다.

#### routes.extend.include

<p>
**타입:** `{ pattern: string }[]`<br />
**기본값:** `undefined`
</p>

Cloudflare 어댑터가 요청 시 생성할 추가 경로를 `routes.extend.include` 배열에 구성합니다.

#### routes.extend.exclude

<p>
**타입:** `{ pattern: string }[]`<br />
**기본값:** `undefined`
</p>

주문형 렌더링에서 제외할 경로를 `routes.extend.exclude` 배열에 구성합니다. 대신 이러한 경로는 사전 렌더링되어 정적으로 제공되며 SSR 함수를 호출하지 않습니다. 또한 이 옵션을 사용하면 SSR 함수를 통해 요청을 라우팅하지 않고도 정적 자산 (예: 이미지, 글꼴, CSS, js, html, txt, json 등) 파일을 직접 제공할 수 있습니다.

```js title="astro.config.mjs"
export default defineConfig({
  adapter: cloudflare({
    routes: {
      extend: {
        include: [{ pattern: '/static' }], // 주문형 렌더링을 위해 사전 렌더링된 페이지를 SSR 함수로 라우팅합니다.
        exclude: [{ pattern: '/pagefind/*' }], // 빌드 시 정적으로 생성되는 Starlight의 pagefind 검색을 사용합니다.
      }
    },
  }),
});
```

### `wasmModuleImports`

<p>

**타입:** `true | false`<br />
**기본값:** `false`
</p>

`.wasm?module` import 구문을 사용하여 `.wasm` 파일을 [ES 모듈로 직접 가져올지](https://github.com/WebAssembly/esm-integration/tree/main/proposals/esm-integration) 여부입니다.

`astro build` 및 `astro dev` 모두에서 이 기능을 활성화하려면 `astro.config.mjs` 파일에 `wasmModuleImports: true`를 추가하세요. [Wasm 모듈 사용](#wasm-모듈-사용)에 대해 자세히 알아보세요.


```js title="astro.config.mjs" ins={6}
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
     wasmModuleImports: true
  }),
  output: 'server'
})
```

## Cloudflare 런타임

Cloudflare 런타임은 환경 변수와 Cloudflare 바인딩에 대한 액세스를 제공합니다. Cloudflare 런타임은 `wrangler` 및 `.dev.vars` 구성 파일에 있는 바인딩을 사용합니다.

### 사용

예를 들어, `wrangler.toml` 파일에 [환경 변수](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) 구성이 설정된 경우:


```toml title="wrangler.toml"
[vars]
MY_VARIABLE = "test"
```

환경 변수 외에 `secrets`도 정의해야 하는 경우 Astro 프로젝트의 루트에 `.dev.vars` 파일을 추가해야 합니다.

```ini title=".dev.vars"
DB_PASSWORD=myPassword
```

다음과 같이 Astro 로컬을 사용하여 바인딩에 액세스할 수 있습니다.

```astro title="src/pages/index.astro"
---
const { env } = Astro.locals.runtime;
---
```

`context.locals`를 통해 API 엔드포인트에서 런타임에 액세스할 수 있습니다.

```js title="src/pages/api/someFile.js"
export function GET(context) {
  const runtime = context.locals.runtime;

  return new Response('Some body');
}
```

`MY_VARIABLE` 바인딩의 값에 액세스하려면 코드에 다음을 추가하세요.

```astro title="src/pages/index.astro"
---
const { env } = Astro.locals.runtime;
const myVariable = env.MY_VARIABLE;
---
```

Cloudflare 문서에서 [지원되는 모든 바인딩 목록](https://developers.cloudflare.com/workers/wrangler/api/#supported-bindings)을 참조하세요.

### 타입 설정

`wrangler`는 바인딩을 위한 TypeScript 타입을 생성하는 `types` 명령을 제공합니다. 이를 통해 수동으로 타입을 설정하지 않고도 locals의 타입을 설정할 수 있습니다. 자세한 내용은 [Cloudflare 문서](https://developers.cloudflare.com/workers/wrangler/commands/#types)를 참조하세요.

구성 파일 (예: `wrangler.toml`, `.dev.vars`)을 변경할 때마다 `wrangler types`를 실행해야 합니다.

:::note
자동으로 다른 명령보다 먼저 `wrangler types`를 실행하는 pnpm 스크립트를 만들 수 있습니다.

```json title="package.json"
{
  "scripts": {
    "dev": "wrangler types && astro dev",
    "start": "wrangler types && astro dev",
    "build": "wrangler types && astro check && astro build",
    "preview": "wrangler types && astro preview",
    "astro": "astro"
  }
}
```
:::

`Runtime`을 사용하여 `runtime` 객체의 타입을 설정할 수 있습니다.

```ts title="src/env.d.ts"
/// <reference types="astro/client" />

type Runtime = import('@astrojs/cloudflare').Runtime<Env>;

declare namespace App {
  interface Locals extends Runtime {
    otherLocals: {
      test: string;
    };
  }
}
```

## Cloudflare 플랫폼

### Headers

Astro 프로젝트의 `public/` 폴더에 `_headers` 파일을 추가하여 [사용자 정의 헤더](https://developers.cloudflare.com/pages/platform/headers/)를 응답에 첨부할 수 있습니다. 이 파일은 빌드 출력 디렉터리에 복사됩니다.

### Assets
Astro가 빌드한 자산은 모두 해시로 이름이 지정되므로 긴 캐시 헤더가 제공될 수 있습니다. 기본적으로 Cloudflare의 Astro는 이러한 파일에 대한 헤더를 추가합니다.

### Redirects

Cloudflare Pages를 사용하여 [사용자 지정 리디렉션](https://developers.cloudflare.com/pages/platform/redirects/)을 선언할 수 있습니다. 이를 통해 요청을 다른 URL로 리디렉션할 수 있습니다. Astro 프로젝트의 `public/` 폴더에 `_redirects` 파일을 추가할 수 있습니다. 이 파일은 빌드 출력 디렉터리에 복사됩니다.

### Routes

[Cloudflare 라우팅](https://developers.cloudflare.com/pages/platform/functions/routing/#functions-invocation-routes)은 `_routes.json` 파일을 사용하여 어떤 요청이 SSR 함수로 라우팅되는지, 어떤 요청이 정적 자산으로 제공되는지 결정합니다. 기본적으로 `_routes.json` 파일은 프로젝트의 파일 및 구성을 기반으로 자동으로 생성됩니다.

어댑터 구성에서 [추가 라우팅 패턴을 지정](#routesextend)하거나 사용자 정의 `_routes.json` 파일을 생성하여 자동 생성을 완전히 재정의할 수 있습니다.

#### 사용자 정의 `_routes.json`

사용자 정의 `public/_routes.json`파일을 생성하면 자동 생성이 재정의됩니다. 자세한 내용은 [사용자 지정 `_routes.json` 생성에 대한 Cloudflare 문서](https://developers.cloudflare.com/pages/platform/functions/routing/#create-a-_routesjson-file)를 참조하세요.

## Wasm 모듈 사용

다음은 요청의 숫자 매개변수를 함께 추가하여 요청에 응답하는 Wasm 모듈을 가져오는 예시입니다.

```js title="pages/add/[a]/[b].js"
import mod from '../util/add.wasm?module';

// 모듈을 공유하기 위해 미리 인스턴스화
const addModule: any = new WebAssembly.Instance(mod);

export async function GET(context) {
  const a = Number.parseInt(context.params.a);
  const b = Number.parseInt(context.params.b);
  return new Response(`${addModule.exports.add(a, b)}`);
}
```

이 예시는 사소하지만 Wasm을 사용하면 이미지 처리 라이브러리 내장과 같은 중요한 I/O를 포함하지 않는 계산 집약적인 작업을 가속화할 수 있습니다.

## Node.js 호환성

기본적으로 Cloudflare는 Node.js 런타임 API를 지원하지 않습니다. 일부 구성에서는 Cloudflare가 Node.js 런타임 API의 하위 집합을 지원합니다. Cloudflare의 [문서](https://developers.cloudflare.com/workers/runtime-apis/nodejs)에서 지원되는 Node.js 런타임 API를 찾을 수 있습니다.

이러한 API를 사용하려면 페이지 또는 엔드포인트가 서버 측에서 렌더링되어야 하며 (사전 렌더링되지 않음) `import {} from 'node:*'` 가져오기 구문을 사용해야 합니다.

```js title="pages/api/endpoint.js"
export const prerender = false;
import { Buffer } from 'node:buffer';
```

또한 `node:*` import 구문을 허용하려면 astro 구성에서 `vite` 구성을 수정해야 합니다.

```js title="astro.config.mjs" ins={7-11}
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({}),
  output: 'server',
  vite: {
		ssr: {
			external: ['node:buffer'],
		},
	},
})
```

Additionally, you'll need to follow Cloudflare's documentation on how to enable support. For detailed guidance, please refer to the [Cloudflare documentation on enabling Node.js compatibility](https://developers.cloudflare.com/workers/runtime-apis/nodejs#enable-nodejs-with-pages-functions).

또한 활성화를 지원하는 방법에 대한 Cloudflare 문서를 따라야 합니다. 자세한 지침은 [Node.js 호환성 활성화에 대한 Cloudflare 문서](https://developers.cloudflare.com/workers/runtime-apis/nodejs#enable-nodejs-with-pages-functions)를 참조하세요.


:::note[패키지 호환성에 미치는 영향]
프로젝트가 Node.js 런타임 API를 사용하는 서버로 패키지를 가져오는 경우, Cloudflare에 배포할 때 문제가 발생할 수 있습니다. 이 문제는 `node:*` import 구문을 사용하지 않는 패키지에서 발생합니다. 패키지가 위 import 구문을 지원하는지 확인하기 위해 패키지 작성자에게 문의하는 것이 좋습니다. 패키지가 이를 지원하지 않으면 다른 패키지를 사용해야 할 수도 있습니다.
:::

## Wrangler로 미리보기

[`wrangler`](https://developers.cloudflare.com/workers/wrangler/)를 사용하여 애플리케이션을 로컬에서 실행하려면 미리 보기 스크립트를 업데이트하세요.

```json title="package.json"
"preview": "wrangler pages dev ./dist"
```

[`wrangler`](https://developers.cloudflare.com/workers/wrangler/)를 사용하면 [Cloudflare 바인딩](https://developers.cloudflare.com/pages/platform/functions/bindings), [환경 변수](https://developers.cloudflare.com/pages/platform/functions/bindings/#environment-variables), [cf 객체](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties)에 액세스할 수 있습니다. Wrangler와 함께 작동하도록 핫 리로드 또는 astro dev 서버를 사용하려면 사용자 정의 설정이 필요할 수 있습니다. [커뮤니티 예시](https://github.com/withastro/roadmap/discussions/590)를 참조하세요.

### 의미 있는 오류 메시지

현재 Wrangler에서 애플리케이션을 실행하는 동안 발생하는 오류는 코드 축소로 인해 그다지 유용하지 않습니다. 더 나은 디버깅을 위해 `astro.config.mjs` 파일에 `vite.build.minify = false` 설정을 추가할 수 있습니다.

```js title="astro.config.mjs" ins={4-8}
export default defineConfig({
  adapter: cloudflare(),
  output: 'server',
  vite: {
    build: {
      minify: false,
    },
  },
});
```

[astro-integration]: /ko/guides/integrations-guide/
